מפרט טכני - שירות נתוני ארנונה

---

1) סיכום מנהלים

שירות הארנונה מאפשר לאזרחים לבדוק את מצב החובות והתשלומים שלהם לארנונה ברשויות המקומיות. השירות פועל כגשר בין האזרח לבין מערכות המידע של הרשויות, ומאפשר קבלת מידע מפורט על נכסים, חובות, הנחות ותשלומים.

ערך עסקי: השירות חוסך זמן הן לאזרחים והן לרשויות, מפחית את מספר הפניות לשירות הלקוחות. ומאפשר תשתית לשירותים נוספים

זרימת עבודה פשוטה:

1. האזרח נכנס לאזור האישי,ואזור אישי פונה למוני service
2. מוני service קולט את הנתונים וממיר אותם
3. מוני service פונה לספק בשביל קבלת נתוני הארנונה
4. מוני service מעבד את המידע ומארגן אותו
5. מוני service מחזיר לאזרח מידע מפורט על כל הנכסים והחובות שברשותו

---

2) תכונות

תכונות עיקריות:

• בדיקת חובות ארנונה - קבלת מידע מפורט על כל הנכסים של האזרח
• הצגת תשלומים - היסטוריית תשלומים עם סטטוס (שולם/לא שולם)
• הנחות ארנונה - רשימת הנחות זמינות עם אחוזים ותקופות
• מידע נכס - כתובת מלאה, גודל, תאריך אכלוס, בעלים
• תשלום אונליין - לינקים ישירים לתשלום
• המרת נתונים - המרה אוטומטית של קודי רשות וזהות לפי הצורך

דוגמאות יומיומיות:

• אזרח רוצה לבדוק חובות: שולח מספר זהות וקוד רשות → מקבל רשימת נכסים עם חובות
• תשלום חוב: לוחץ על לינק התשלום → מועבר לאתר התשלום של הרשות
• בדיקת הנחות: רואה אילו הנחות זמינות לו (פנסיונר, נכה, וכו')
• מידע נכס: רואה כתובת מלאה, גודל, תאריך אכלוס

---

3) מדריך שימוש מהיר

דוגמת בקשה:

curl -X GET "http://localhost:3001/api/v1/muni/services/arnona/payerArnonaInfo?tzNum=222222222&semel_moeza=999" \
  -H "Authorization: Bearer YOUR_TOKEN"

פרמטרים נדרשים:

• tzNum (חובה): מספר זהות (5-10 ספרות)
• semel_moeza (אופציונלי): קוד מועצה (1-6 ספרות)
• semel_yeshuv (אופציונלי): קוד ישוב (1-6 ספרות)

דוגמת תשובה:

{
  "tz": "222222222",
  "municipality_code": 999,
  "municipality_name": "תל אביב-יפו",
  "assets": [
    {
      "asset_id": "12345",
      "full_address": "רחוב הרצל 1 תל אביב",
      "type_description": "דירה",
      "size": 80,
      "balance": 1500.50,
      "payment_records": [
        {
          "number": "001",
          "amount": 500,
          "status": "שולם",
          "payment_link": "https://payment.example.com"
        }
      ]
    }
  ]
}

---

4) תיאור זרימת עבודה

4.1 ארבעת הזרימות (Gisonim)

זרימה 1: מהמערך הדיגיטל → שירות מוני

מה מפעיל את הזרימה:

• בקשה HTTP מגיעה ל-ArnonaController
• פרמטרים: tzNum, semel_moeza או semel_yeshuv

מה קורה בזרימה:

1. בדיקת תקינות: וידוא שמועבר לפחות אחד מהפרמטרים הנדרשים
2. המרת קוד רשות: אם מועבר semel_yeshuv, המרה ל-semel_moeza
3. בדיקת המרת זהות: אם DEV_CONVERTING_TZ=true, המרת זהות וקוד רשות
4. יצירת אובייקט בקשה: ArnonaInfoReq עם הנתונים המעודכנים

נתונים שעוברים:

• tzNum → tz
• semel_moeza או semel_yeshuv → muniCode

טיפול בשגיאות:

1. BadRequestException אם חסרים פרמטרים
2. NotFoundException אם קוד רשות לא נמצא
3. HttpException אם יש שגיאה בהמרה

מה מוחזר:

• אובייקט ArnonaInfoReq מוכן לעיבוד

זרימה 2: משירות מוני → ספק

מה מפעיל את הזרימה:

• קריאה ל-arnonaService.getPayerArnonaInfo()

מה קורה בזרימה:

1. קריאה לשירות חיצוני: arnonaInfoService.getPayerArnonaInfo()
2. חיפוש במסד נתונים: חיפוש שירות "ArnonaInfo" ב-MongoDB
3. בדיקת זמינות רשות: וידוא שהרשות תומכת בשירות
4. בדיקת סטטוס שירות: וידוא שהשירות לא מוקפא
5. קבלת פרטי ספק: שם ספק ונתוני חיבור
6. שליחה לספק: קריאה ל-supplierAuthServiceService.fetchDataFromSupplierApi()

נתונים שעוברים:

• tz (מספר זהות)
• municipality_code (קוד רשות)
• supplierName (שם הספק)
• serviceCode ("ArnonaInfo")

טיפול בשגיאות:

{
    "90": "אין שירות פעיל ברשות המקומית. לבירורים ניתן לפנות ישירות לרשות המקומית",
    "101": "לא נמצא משלם פעיל במערכת רשות מקומית",
    "102": "לא נמצא רשות ",
    "103": "פורמט תז שגוי",
    "104": "פורמט קוד רשות שגוי",
    "105": "לא נמצאו נכסים למשלם פעיל",
    "120": "תקלת איתור נתונים ברשות המקומית",
    "150": "יש תקלת שירות ברשות המקומית"
}

מה מוחזר:

• תשובה מהספק עם isDirectus flag
• שם רשות מעודכן

זרימה 3: מספק → שירות מוני

מה מפעיל את הזרימה:

• תשובה חוזרת מהספק (Directus או ספק אחר)

מה קורה בזרימה:

1. קבלת תשובה גולמית: נתונים לא מעובדים מהספק
2. בדיקת קוד שגיאה: אם יש error_code, יצירת תשובת שגיאה
3. זיהוי מקור נתונים: בדיקת isDirectus flag
4. עיבוד נתונים:
   • אם Directus: סינון לפי muniCode ו-tz, מיפוי לשדות נדרשים
   • אם ספק אחר: בניית כתובת מלאה, המרת סטטוס תשלום, שרשור הנחות

נתונים שעוברים:

• נתונים גולמיים מהספק
• isDirectus flag
• error_code (אם יש)

טיפול בשגיאות:

• יצירת PayerArnonaInfo עם נתונים ריקים אם יש error_code
• תרגום קוד שגיאה להודעה בעברית
• HttpException אם יש שגיאה בעיבוד

מה מוחזר:

• אובייקט PayerArnonaInfo מעובד ומוכן

זרימה 4: משירות מוני → המערך הדיגיטל

מה מפעיל את הזרימה:

• השלמת עיבוד הנתונים ב-ArnonaService

מה קורה בזרימה:

1. המרה לאובייקט DTO: plainToInstance(PayerArnonaInfo, transformedData)
2. וידוא מבנה נתונים: בדיקה שהתשובה תואמת למבנה הנדרש
3. החזרת תשובה: שליחת PayerArnonaInfo ל-Controller
4. טיפול בשגיאות: אם יש שגיאה, החזרת HttpException מתאימה

נתונים שעוברים:

• PayerArnonaInfo מוכן עם כל השדות
• municipality_code, tz, municipality_name
• מערך assets עם כל הפרטים

טיפול בשגיאות:

• HttpException עם הודעת שגיאה מתאימה
• לוג של השגיאה לקונסול

מה מוחזר:

• תשובה JSON מוכנה ללקוח
• קוד סטטוס HTTP מתאים

4.2 בדיקת Directus (שרת דמה)

מתי נקרא:

• כאשר rawData.isDirectus === true
• זה קורה כאשר הספק הוא Directus (שרת דמה לבדיקות)

מה נבדק שם:

1. סינון נתונים: רק נכסים שמתאימים ל-muniCode ו-tz הנוכחיים
2. מיפוי שדות: המרת שדות Directus למבנה הסטנדרטי
3. עיבוד הנחות: המרת מערך הנחות לפורמט נדרש
4. עיבוד תשלומים: המרת רשומות תשלום לפורמט נדרש

תפקיד בזרימה הכללית:

• בדיקות ופיתוח: מאפשר בדיקת מוני service ללא חיבור לספקים אמיתיים
• נתונים דמה: מספק נתונים קבועים לבדיקות
• ולידציה: מאפשר לוודא שמוני service עובדת נכון לפני חיבור לספקים אמיתיים

פרטי החיבור:

• URL: https://directus.muni-dev.linnovate.net (פיתוח)
• Token: 7WyKFGAyRvd5iQlxFxyoz-nn7S_lm0Lo
• Collection: Municipalities
• Filters: municipality_code ו-persons (ת.ז.)

---

5) תלויות חיצוניות ושירותים

שירותים פנימיים:

• MunicipalitiesService: ניהול רשויות וישובים, המרת קודים
• ArnonaInfoService: חיבור לספקים חיצוניים
• SupplierAuthServiceService: אימות ושליחה לספקים
• MongodbServiceService: גישה למסד נתונים
• I18nService: תרגום הודעות שגיאה

שירותים חיצוניים:

• Directus: שרת דמה לבדיקות (https://directus.muni-dev.linnovate.net)
• ספקים אמיתיים: Metropoline, epr (עדיין לא מוגדרים)

מסדי נתונים:

• MongoDB: אחסון רשויות, שירותים, ונתוני חיבור לספקים

---

6) הגדרות וסביבה

משתני סביבה:

• DEV_CONVERTING_TZ: true/false - האם להמיר זהות וקוד רשות
• DemoProvider_url: כתובת Directus לבדיקות
• DemoProvider_token: טוקן אימות ל-Directus
• mongo_conn: חיבור MongoDB

הגדרות API:

• Port: 3001 (API), 3002 (Arnona)
• Base URL: /api/v1/muni/services/arnona
• Authentication: OAuth2 Bearer Token
• Validation: class-validator עם ValidationPipe

---

7) מבני נתונים / DTOs / מודלים

ArnonaInfoReqDTO (קלט):

{
  tzNum: string;        // מספר זהות (5-10 ספרות)
  semel_moeza?: string; // קוד מועצה (1-6 ספרות)
  semel_yeshuv?: string; // קוד ישוב (1-6 ספרות)
}

PayerArnonaInfo (פלט):

{
  errorcode?: number;           // קוד שגיאה
  errormsg?: string;           // הודעת שגיאה
  tz: string;                  // מספר זהות
  municipality_code: number;    // קוד רשות
  municipality_name?: string;   // שם רשות
  assets: Asset[];             // מערך נכסים
}

Asset (נכס):

{
  asset_id: string;            // מספר נכס
  full_address: string;        // כתובת מלאה
  type_description: string;    // תיאור נכס
  size?: number;              // גודל נכס
  start_date?: Date;          // תאריך אכלוס
  balance?: number;           // יתרה לתשלום
  payer_id: string;           // מספר משלם
  contact_property: string;    // קשר משלם
  payer_name: string;         // שם משלם
  owner_tz?: string;          // ת.ז. בעל נכס
  owner_name?: string;        // שם בעל נכס
  tenants?: number;           // מספר נפשות
  discounts_description?: string; // תיאור הנחות
  payment_records: PaymentRecord[]; // רשומות תשלום
  discounts?: Discount[];      // מערך הנחות
}

---

8) טיפול בשגיאות ומקרי קצה

קודי שגיאה:

• 90: שירות לא נמצא, רשות לא תומכת, או שירות מוקפא
• 400: בקשה לא תקינה (חסרים פרמטרים)
• 404: רשות לא נמצאה
• 500: שגיאת שרת פנימית

מקרי קצה:

• זהות לא תקינה: בדיקת regex (5-10 ספרות)
• קוד רשות לא קיים: בדיקה ב-MongoDB
• נתונים חסרים: החזרת מבנה ריק עם הודעת שגיאה
• שגיאת רשת: timeout או חיבור נכשל לספק
• נתונים לא תקינים: validation של DTOs

טיפול בשגיאות:

• לוגים: כל שגיאה נרשמת לקונסול
• הודעות בעברית: תרגום קודי שגיאה להודעות ברורות
• תשובות עקביות: מבנה אחיד גם במקרה של שגיאה

---

9) אבטחה ואישור

אימות:

• OAuth2Guard: חובה לכל הבקשות
• Bearer Token: בטוקן ב-Header
• ValidationPipe: בדיקת תקינות פרמטרים

הרשאות:

• שירות ציבורי: כל משתמש מאומת יכול לגשת
• ללא הרשאות מיוחדות: לא נדרשות הרשאות נוספות

הגנות:

• SQL Injection: שימוש ב-MongoDB עם Mongoose
• XSS: בדיקת regex על שדות טקסט
• Validation: בדיקת כל הפרמטרים לפני עיבוד

---

10) בדיקות

בדיקות יחידה:

• ArnonaController: בדיקת validation, error handling
• ArnonaService: בדיקת עיבוד נתונים, טיפול בשגיאות
• MunicipalitiesService: בדיקת המרת קודים

בדיקות אינטגרציה:

• חיבור MongoDB: בדיקת חיבור וקריאה
• חיבור Directus: בדיקת שליחה וקבלת תשובה
• עיבוד נתונים: בדיקת המרה מלאה end-to-end

בדיקות E2E:

• API endpoints: בדיקת בקשות מלאות
• Error scenarios: בדיקת טיפול בשגיאות
• Data transformation: בדיקת עיבוד נתונים

---

11) לוגים וניטור

לוגים:

• LoggingInterceptor: כל בקשה ותשובה
• Console.error: שגיאות בעיבוד נתונים
• MongoDB connection: סטטוס חיבור

ניטור:

• Request/Response: זמן תגובה, קוד סטטוס
• Error rates: אחוז שגיאות לפי סוג
• Performance: זמני עיבוד נתונים

מטריקות:

• Success rate: אחוז בקשות מוצלחות
• Response time: זמן תגובה ממוצע
• Error distribution: התפלגות שגיאות

---